CD Ware Multimedia 1994 November

home *** CD-ROM | disk | FTP | other *** search

/ CD Ware Multimedia 1994 November / Cd Ware (Nro. 2) - Epimundo.iso / DOS / PG / SNAP31.ZIP / SNAP_P.DOC < prev next >

Wrap

Text File | 1994-04-25 | 32.6 KB | 859 lines

SNAP_P StaNdArd Printer for Pascal COPYRIGHT⌐ 1992, 1993, 1994 JAMES L. ALLISON ALL RIGHTS RESERVED James L. Allison Neptune Systems 1703 Neptune Lane Houston, TX 77062 (713) 488-5722 Voice (713) 486-0375 FAX CompuServe (71565,303) Page - 1 Why Use SNAP_P Rapid evaluation, cost savings and debugging ease are the main reasons for using a standard printer. If you are working with a group of programmers, a standard source code format makes reading, managing, integrating and maintaining your product far less expensive and more reliable. Everyone can read everyone else's code. Turnover becomes less of a headache. If you import code from outside ( another department, a technical journal or a BBS ) the ability to snap that code into your own format is critical for evaluation. If you are working alone a standard printer gets all of your source into a format that you will be able to read months after you forgot why you wrote it in the first place. If you are in school a standard printer will give your reports the professional look that instructors respect. The biggest advantage is that structural errors in a program appear instantly in a listing that has uniform indentation and capitalization. It is far easier to write error-free code when you can see what you are doing. The best debugger is a standard printer. About SNAP_P For safety, SNAP_P will not change the original source file unless told to. Even then, a backup copy will be made first. The newly structured source text will be placed in a file with the same name as the original and the default extension ".SNP". The Resulting formatted code is shown beside the original on your screen for easy comparison. If you like the results and you have not told SNAP_P to change the source, you can replace the original ".PAS" file with the new file yourself. SNAP_P reformats a Pascal program by adjusting margins and internal spacing, and using standard capitalization for all keywords and identifiers. You may specify capitalization by either rules or by table lookup. If you choose "rules" (rather than "table") the standard capitalization is used. You can specify which standards and use different rules for keywords and identifiers. If you choose table lookup an optional dictionary of standard capitalization is maintained by SNAP_P. String literals and comments are never changed. You can protect blocks from any adjustment by using the echo mode described later. Installation This is a manual installation procedure. There is a growing dislike of automatic procedures that do strange, unknown things to the system. (Too many times have I had to use a full backup tape to get rid of a program I decided not to keep. I hope you feel the same way.) The distribution disk contains two versions of SNAP_P: SNAP_PD for DOS and SNAP_PW for Windows. You may use either (or both) of Page - 2 these of these. The operation of the two versions is virtually identical. This manual discusses the Windows version, with notes where the DOS version differs. SNAP_P will write several files during normal operation. The capitalization dictionary (SNAP_P.CAP) and the optional settings (SNAP_P.INI) will be written to the same directory where the .EXE file is placed. In batch mode SNAP_P will create a scratch file and a log file in this directory. It will also place a file containing the registration form in this directory if requested. Reformatted files (.SNP) and backup files are written to the directory where the original source was found. If you use both the DOS and Windows versions, they should be placed in the same directory so the dictionary and preference files will be shared. You should create a directory (SNAP_P, or whatever you like) on your disk to hold these files. Copy the SNAP_Px.EXE files to the same directory on your hard disk. If you want to execute from anywhere in the system you need to make sure it is in the PATH. For DOS: If you want to use SNAP_P as a tool in a Borland(R) product, do the following: 1 Start the Borland product 2 Under the Options|Tools menu select New 3 On the resulting form enter: Title : ~S~NAP_P Program Path : Enter the full path name of SNAP_P.EXE Command Line : $EDNAME $SAVE ALL Hot Keys : Pick an available Hot Key (optional). 4 Click OK For Windows: Use Windows Setup|Options|Set Up Applications to create an item in a convenient group. The group containing the compiler and workbench is a natural place. Removal If you decide that you don't want to keep SNAP_P on your system, delete SNAP_P*.* from the directory where you placed SNAP_Px.EXE. If you created a special directory for SNAP_P, just delete the whole thing. If you have changed your PATH or modified any tools menus or program groups these will also need to be returned to their original state. Using SNAP_P The command line syntax is: SNAP_Px [[path]filename.ext [ /brs]] Example: SNAP_PD myprog.pas Example: SNAP_PD myprog.pas /bp Example: SNAP_PW Page - 3 If the filename is given, SNAP_P opens a window containing that file at startup, unless the /b switch is specified. The /b switch indicates batch mode. There must be a space between the filename and the /b switch. These switches are not case sensitive. The other switches allowed in batch mode are: s Silent: do not show progress during run r Replace existing backup file. If this is not present, a backup copy will not be made if it would overwrite an existing backup. This is for safety. The first time SNAP_P is used on a source file, a backup copy is made. As you experiment with the options, you want to keep the original intact. In batch mode all options are those that have been specified, except that prompting for new words is suppressed. The original source is saved as described below and a filename.snp file is not created. All messages are placed in SNAP_P.LOG in the SNAP_P directory. The DOS version of SNAP_P is a Turbo Vision(R) application, so if you are familiar with the Borland interface you should have no problems. If you use a mouse the interface is standard with pull-down menus, check boxes, radio buttons and text entry boxes. If you prefer a keyboard, press F10 to highlight the menu bar and use the arrow and tab keys to move around. Use the space bar to toggle check boxes. You may also use Alt-?, where ? is the highlighted letter on the menu bar. The status bar at the bottom of the screen gives some helpful keystrokes to get you started. (DOS - The number in the lower right corner of the screen is the available memory. Keep an eye on this, especially when working with large files.) Install SNAP_P and start it as described above. Open a file using the Open option on the File pull-down menu. Set capitalization rules. The rules stay in effect for each file you reformat until explicitly changed. Set options to use. The options stay in effect for each file you reformat until explicitly changed. Re-format the code. You may repeat these steps as needed to achieve the desired results. You should work in the interactive mode until you get a feel for what all of the options do, and have established a set that you like. Page - 4 Explanation of Menu Options The menu bar has five pull-down items. File: Open: Open a file (directory menu provided) Exit: Exit SNAP_P Window: Tile: Tile open windows Cascade: Cascade open windows Control: General: Margins, indentation, etc. Spaces: Space before and after punctuation "if" Statements: if-then-else structure Block Structure: begin-end, case, loop structures Capitalization Rules: Capitalization rules, dictionary use Reset to Defaults: Reset all options to default values SNAP: Reformat Source: Re-format source in active window Replace Original File: Backup original file, replace with new text. Page - 5 About: Product Support: Where to get support. Ombudsman: ASP contact for help Copyright: Copyright notice Registration: Create a registration form. General Dialog Box Scratch File Extension: SNAP_P will place the reformatted text in a file with the same name as the source, and the given extension. The file will be in the same directory as the original. The purpose of this file is to give you a chance to look at the result and compile it to make sure everything is OK. Backup Extension Char: If you replace the original file, SNAP_P will make a backup copy of the original in a file with the same name as the source. The extension will be formed by replacing the first character of the source extension with the given character. For example, PROG.PAS will be saved as PROG.~AS. The backup file will be placed in the same directory as the original. If a backup already exists, it will not be replaced unless you say so. Indent Spaces: indent this many spaces when indent is specified. Line Wrap Indent: indent this many more spaces for continuation lines. Minimum Line Length: stop indenting when lines get this short. Wrap to Punctuation: if multiple lines are needed, attempt to start the continuation lines after the first one of " =" ":" ":=" "(" on the first line. If this is not possible, use the setting in Line Wrap Indent. Blank Line After Wrap: If continuation lines are needed insert a blank line after the last one. Left Margin: insert this many spaces before each line. Right Margin: last character position used. Note: If a comment or literal (or anything else) will not fit between the left and right margins the line will be written, ignoring the margin settings. Break Line: insert a highly visible comment line at certain places in the output. The line runs from the left to the right margin. Break lines are placed in the following locations: (1) before "implementation", (2) before top level subprograms, (3) before unit initialization "begin" statements, (4) before main program "begin" statements. Break lines are not placed before subprograms nested inside other subprograms. This can help considerably when reading someone else's code. Filler: fill character used to form a break line. Note: Fill lines are deleted during the parse and inserted during the write. A break line is recognized by starting with "(*" and ending with "*)" with nothing but fill characters in between. If you want to change the fill character for a file that already contains break lines, you must first reformat with break lines turned off to remove the old lines, change the fill character, turn break lines back on, and finally reformat again. If there aren't many of them you can delete them by hand. Page - 6 Pad "function", etc.: add blank characters on the right to make "function", "procedure", "constructor" and "destructor" all the same length. This is only in effect during an object type definition or the interface part of a unit. This can provide a neater appearance in object type definitions. Keep Blank Lines: retain blank lines from the original. If this is in effect all of the options to insert blank lines will be ignored. UpCase GOTO, EXIT, etc.: shift all "jumps" to upper case. These are GOTO, EXIT, HALT, BREAK and CONTINUE. If this box is checked, it overrides all other case settings for these words. Blank line before "with": insert a blank line before a "with" statement. Do not reformat interface part of a unit.: Very often the interface to a unit has been carefully hand crafted for readability. It is usually the only part of a unit the end user ever sees. Check this box if you want to leave the interface alone. Spaces Dialog Box These control spacing within a line. Pick the options that you prefer. 'if' Statements Dialog Box There are many differences of opinion about how an "if" statement should be written. The defaults are for a full "comb" structure. This provides very readable text, and the program structure is obvious at a glance, but many feel that it takes up too much space on the page. Another common pattern is produced by turning off all options except for Newline Before "else". Take for example the following: function isAlpha(C: char): boolean; begin if C in ['A' .. 'Z', 'a' .. 'z'] then isAlpha := true else isAlpha := false; end; Page - 7 or, if Cp > Length(Line) then begin Block^.Append(Buf); Buf := ''; Next_Line; end else begin Buf := Buf + Line[Cp]; BumpCp; end; These code fragments show what the default settings will produce. The "then" and "else" parts remain indented and aligned, no matter how complex the structure. When you are experimenting with these you may get some unexpected results. In particular if you turn off the Newline after "then" or "else", you probably want to turn off the corresponding indent. The Blank Line After option inserts a blank line after the entire "if-then-else" structure. If Keep Blank Lines is checked in the General menu, the Blank Line Before/After is ignored. Block Structure Dialog Box This menu controls the layout of blocks. Check the boxes that give you the appearance you like. Indent: indent the text inside the block Blank Line Before: insert a blank line before the beginning of the block. Blank Line After: insert a blank line after the block. Note: the blank line is after the block, not after the statement. For example, in a "case" statement the blank line is after the corresponding "end", not after the "case". For a "repeat" statement, the blank line is after the "until" line. If Keep Blank Lines is checked in the General menu, the Blank Line Before/After is ignored. The Blank Line Before/After option will never produce two blank lines together. For example, if you check both Before and After for case statements, and your program has two case statements together, there will be only one blank line between them. Indenting subprograms is very useful, especially if the file contains nested (local) functions or procedures. Code readability is vastly improved in these cases. Page - 8 Declarations are not blocks in the "block structured" sense of the word. These are best explained by example. type Switch = string[MaxSwitchLength]; Operation = (CommandLine, Interactive); const OPMode: Operation = Interactive; var InLines: PLineCollection; OutFile: text; LineNo: integer; This segment of code was produced using the default settings for declarations. That is, they have Blank Line Before, Blank Line After, and Indent turned on. Capitalization Rules Dialog Box Upper: All upper case (example: MY_VARIABLE). Lower: All lower case (example: my_variable). Cap: First letter and all letters following an underscore are upper case, others in lower case (example: My_Variable). As is: Do not change. Use Dictionary: Use the dictionary for capitalization. This is how you control names such as "mfOKButton" etc. Prompt for new words: If you are using the dictionary and SNAP_P encounters an identifier not in the dictionary, you will be prompted for the capitalization and the word will be added to the dictionary. If this box is not checked the rules for identifiers will be used for new words, and the new words will not be added to the dictionary. This is always turned off during batch operation. Reserve Directives: Directives (virtual, forward, etc.) are not reserved words, but many programmers treat them as such. Borland strongly recommends that directives never be used as identifiers. I agree. Check the box if you want to treat directives as reserved words. If you do not check the box they will be treated as identifiers. About Comments Comments are always difficult in a pretty printer; they follow no rules. SNAP_P handles comments in the following way. If a comment is the first non-blank on a line, it will start a new line in the output. If it is the last non-blank on a line, it will end a line in the output. A single line comment will remain Page - 9 a single line comment. An embedded comment may or may not get wrapped to a new line, depending on spacing, indents, etc. Multiple line comments have the first and last lines handled according to the above rules, while intermediate lines are copied to the output. About the Dictionary You may want to use table lookup instead of rules for capitalization. For most applications the rules will suffice, but there are cases where you need more control. For example, "ReadLn", "cmCancel", "FileName" and so on follow no particular rules, but you want a standard appearance. This is what the dictionary is for. Each word in the source file is capitalized according to the dictionary. When a new word is found, you will be prompted for the capitalization if Prompt for New Words has been checked. You cannot change the spelling, only the looks of the word. If you enter just a return (enter), the name will be used as is. The dictionary is kept as a text file named SNAP_P.CAP in the directory where you placed the .exe files, so you can edit it whenever you like. The words must be kept in alphabetical order. The order in the dictionary is not case sensitive. If you need to change the looks of a word in the dictionary use any editor to do so, but do not change its location. Do not use a word processor that might introduce extra characters into the file. Use a simple text editor instead. The one you use for source code is OK. Protecting Blocks There are times when you want to protect a block of code from any reorganization. This is especially true for tabular layout. Echo mode turns SNAP_P off entirely. A {+e} inserted as a comment in the source code starts echo mode. From that point on the text is simply copied to the output. It is not even scanned, except to look for a line containing only {-e}, which turns echo mode off. Since echo mode turns off all parsing, echo mode must respect the Pascal block and parenthesis structure. If, for example echo mode includes a "begin" but not the matching "end" the indent structure will be incorrect. The {+e} and {-e} comments must appear by themselves on a line. They are not case sensitive. You can protect the interface to a unit by checking the "Do not reformat interface part of a unit" box in the General dialog under the Control menu. If this is checked the right margin setting will be ignored. Both left and right margins are ignored in echo mode. Page - 10 Restrictions SNAP_P assumes the original file will compile. Tab characters, except in literals, comments and protected blocks are deleted. Null characters are replaced by blanks except in protected blocks. SNAP_P does not recognize conditional compilation. If anything in a conditional compilation would "break" the block structure, echo mode should be used. Control characters in strings may be written using # or ^ notation. SNAP_P recognizes all of the # notation characters, but only ['@'..'_', 'a'..z'] (in hex, this is [$40..$5F, $61..$7A]) in ^ notation. Items such as string literals that will not fit between margins will be placed on a line by themselves. Indent and the right margin will be ignored for that line. There is an internal limit of 2048 characters in the output buffer. If a statement exceeds this length the line will be written at that point and the buffering will start over. The result will be correct, and will compile correctly, but the looks may not be what you would like; the line wrap will look awkward. You may want to echo such statements. You may want to echo "inline" and "asm" blocks. Page - 11 Definition of Shareware Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and continue using it, you are expected to register. Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights, with a few specific exceptions as stated below. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribution. The author specifically grants the right to copy and distribute the software, either to all and sundry or to a specific group. For example, some authors require written permission before a commercial disk vendor may copy their Shareware. Shareware is a distribution method, not a type of software. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware. The Shareware system makes fitting your needs easier, because you can try before you buy. And because the overhead is low, prices are low also. Shareware has the ultimate money-back guarantee -- if you don't use the product, you don't pay for it. Disclaimer - Agreement Users of SNAP_P must accept this disclaimer of warranty: "SNAP_P is supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author assumes no liability for damages, direct or consequential, which may result from the use of SNAP_P." SNAP_P is a "shareware program" and is provided at no charge to the user for evaluation. Feel free to share it with your friends, but please do not give it away altered or as part of another system. The essence of "user-supported" software is to provide personal computer users with quality software without high prices, and yet to provide incentive for programmers to continue to develop new products. If you find this program useful and find that you are using SNAP_P and continue to use SNAP_P after a reasonable trial period, you must make a registration payment of $35.00 to Neptune Systems. The $35.00 registration fee will license one copy of each of the DOS and Windows version for use on any one computer at any one time. You must treat this software just like a book. A book cannot be read by two different persons at the same time. This software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Page - 12 Commercial users of SNAP_P must register and pay for their copies of SNAP_P within 30 days of first use or their license is withdrawn. Site-License arrangements may be made by contacting Neptune Systems. Anyone distributing SNAP_P for any kind of remuneration must first contact Neptune Systems at the address above for authorization. This authorization will be automatically granted to distributors recognized by the (ASP) as adhering to its guidelines for shareware distributors, and such distributors may begin offering SNAP_P immediately (However Neptune Systems must still be advised so that the distributor can be kept up-to-date with the latest version of SNAP_P.) You are encouraged to pass a copy of SNAP_P along to your friends for evaluation. Please encourage them to register their copy if they find that they can use it. All registered users will receive a copy of the latest version of the SNAP_P system without the registration reminder at the beginning and end, and a laser printed copy of this manual with screen capture illustrations. They will also receive free technical support via U.S. mail, CompuServe electronic mail or telephone for a period of six months after registration. Ombudsman This program is produced by a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for members' products. Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442-9427 USA, FAX 616-788-2765 or send a CompuServe message via CompuServe Mail to ASP Ombudsman 70007,3536. Setting options is explained later in this manual. The illustrations in this manual are from the Windows version. The DOS versions are functionally the same. The DOS version also has a status bar at the bottom of the screen. This defines single keystrokes for Exit, Close, Toggle 43/50 line mode and Menu. Page - 13